4 Secret Service API

The Secret Service API is a standard from freedesktop.org to securely store passwords and other confidential information. This API is implemented by system daemons such as the GNOME Keyring and the KDE Wallet (these are GNOME and KDE packages respectively and should be available on most modern GNU/Linux systems).

The auth-source library uses the secrets.el library to connect through the Secret Service API. You can also use that library in other packages, it’s not exclusive to auth-source.

Variable: secrets-enabled

After loading secrets.el, a non-nil value of this variable indicates the existence of a daemon providing the Secret Service API.

Command: secrets-show-secrets

This command shows all collections, items, and their attributes.

The atomic objects managed by the Secret Service API are secret items, which contain things an application wishes to store securely, like a password. Secret items have a label (a name), the secret (which is the string we want, like a password), and a set of lookup attributes. The attributes can be used to search and retrieve a secret item at a later date.

Secret items are grouped in collections. A collection is sometimes called a ‘keyring’ or ‘wallet’ in GNOME Keyring and KDE Wallet but it’s the same thing, a group of secrets. Collections are personal and protected so only the owner can open them.

The most common collection is called "login".

A collection can have an alias. The alias "default" is commonly used so the clients don’t have to know the specific name of the collection they open. Other aliases are not supported yet. Since aliases are globally accessible, set the "default" alias only when you’re sure it’s appropriate.

Function: secrets-list-collections

This function returns all the collection names as a list.

Function: secrets-set-alias collection alias

Set alias as alias of collection labeled collection. Currently only the alias "default" is supported.

Function: secrets-get-alias alias

Return the collection name alias is referencing to. Currently only the alias "default" is supported.

Collections can be created and deleted by the functions secrets-create-collection and secrets-delete-collection. Usually, this is not done from within Emacs. Do not delete standard collections such as "login".

The special collection "session" exists for the lifetime of the corresponding client session (in our case, Emacs’s lifetime). It is created automatically when Emacs uses the Secret Service interface and it is deleted when Emacs is killed. Therefore, it can be used to store and retrieve secret items temporarily. The "session" collection is better than a persistent collection when the secret items should not live longer than Emacs. The session collection can be specified either by the string "session", or by nil, whenever a collection parameter is needed in the following functions.

Function: secrets-list-items collection

Returns all the item labels of collection as a list.

Function: secrets-create-item collection item password &rest attributes

This function creates a new item in collection with label item and password password. attributes are key-value pairs set for the created item. The keys are keyword symbols, starting with a colon. Example:

;;; The session "session", the label is "my item"
;;; and the secret (password) is "geheim"
(secrets-create-item "session" "my item" "geheim"
 :method "sudo" :user "joe" :host "remote-host")

Function: secrets-get-secret collection item

Return the secret of item labeled item in collection. If there is no such item, return nil.

Function: secrets-delete-item collection item

This function deletes item item in collection.

The lookup attributes, which are specified during creation of a secret item, must be a key-value pair. Keys are keyword symbols, starting with a colon; values are strings. They can be retrieved from a given secret item and they can be used for searching of items.

Function: secrets-get-attribute collection item attribute

Returns the value of key attribute of item labeled item in collection. If there is no such item, or the item doesn’t own this key, the function returns nil.

Function: secrets-get-attributes collection item

Return the lookup attributes of item labeled item in collection. If there is no such item, or the item has no attributes, it returns nil. Example:

(secrets-get-attributes "session" "my item")
     ⇒ ((:user . "joe") (:host ."remote-host"))

Function: secrets-search-items collection &rest attributes

Search for the items in collection with matching attributes. The attributes are key-value pairs, as used in secrets-create-item. Example:

(secrets-search-items "session" :user "joe")
     ⇒ ("my item" "another item")

The auth-source library uses the secrets.el library and thus the Secret Service API when you specify a source matching "secrets:COLLECTION". For instance, you could use "secrets:session" to use the "session" collection, open only for the lifetime of Emacs. Or you could use "secrets:Login" to open the "Login" collection. As a special case, you can use the symbol default in auth-sources (not a string, but a symbol) to specify the "default" alias. Here is a contrived example that sets auth-sources to search three collections and then fall back to ~/.authinfo.gpg.

(setq auth-sources '(default
                     "secrets:session"
                     "secrets:Login"
                     "~/.authinfo.gpg"))